---
description: Plasmo offers first-class support for environment variables. Learn how to use them in your browser extension.
---

import { Callout } from "nextra-theme-docs"

# Environment Variables

Plasmo offers first-class support for environment variables. This allows you to customize your extension to fit the need of each browser and development environment from the same codebase.

## Examples

- [with-env](https://github.com/PlasmoHQ/examples/tree/main/with-env)

## Built-in Environment Variables

Plasmo framework provides the following built-in client-side environment variables:

- `NODE_ENV`: Either `development` or `production` depending on the build command
- `PLASMO_TARGET`: The specified target, e.g. `chrome-mv3`, specified by [the `--target` flag](/framework/workflows/build#with-a-specific-target)
- `PLASMO_BROWSER`: The name of the target browser, e.g. `chrome`
- `PLASMO_MANIFEST_VERSION`: The manifest version, e.g. `mv3` or `mv2`
- `PLASMO_TAG`: The build tag, e.g. `dev`, `prod` or a custom one specified by [the `--tag` flag](/framework/workflows/build#with-a-custom-tag)

## Custom Environment Variables

To add environment variables accessible to the extension, create a `.env` file:

<Callout emoji="⚠️">
  Only env vars prefixed with `PLASMO_PUBLIC_` will be injected.
</Callout>

```ini
PLASMO_PUBLIC_SHIP_NAME=ncc-1701
PLASMO_PUBLIC_SHIELD_FREQUENCY=42

PRIVATE_KEY=xxx # Undefined in extension
```

### NODE_ENV Specific Env

To separate environment variables between `dev` and `build`, you can use the following files:

- `.env.development`
- `.env.production`

If there is a `CRX_PUBLIC_KEY` environment variable in `.env.development` but not in `.env.production` or `.env`, it will only be available in `plasmo dev` but not `plasmo build`.

### Bundle Specific Env

Plasmo Framework also provides environment variables specific to a certain [build target](/framework/workflows/build#with-a-specific-target) or [build tag](/framework/workflows/build#with-a-custom-tag) when creating the final bundle. Given the following build command:

```sh
plasmo build --target=safari-mv3 --tag=alpha
```

The following env files will be considered, ordered by priority:

- `.env.safari`
- `.env.alpha`
- `.env`

### Local Env

Plasmo also supports the following environment file names (Next.js developers will find these familiar):

- `.env.<browser>.local`
- `.env.<tag>.local`
- `.env.<NODE_ENV>.local`
- `.env.local`

Files with `.local` at the end of their names have a higher priority than non-local ones. For example, `.env.local` has higher priority than `.env.production` and `.env.development`.

Within the same namespace, however, the cascading order is as expected. This feature utilizes a cascading/overriding strategy for environment variables using the [`dotenv` package](https://www.npmjs.com/package/dotenv).

### Prioritized Env

To include an environment file that is prioritized above all, use the `--env` flag. The name of this file can be named anything:

```sh
plasmo build --env=.env.important
```

## Using Environment Variables

Environment variables are a powerful feature that allow you to customize your extension to fit the needs of each browser and development environment from the same codebase.

### In Source Code

To reference an environment variable in your source code, use the full path `process.env.<ENV_NAME>`. For example:

```tsx
// For TSX (popups, option page):
const FrontHull = () => <h1>{process.env.PLASMO_PUBLIC_SHIP_NAME}</h1>

// For TS (content scripts or background-scripts):
const shield = new Shield(process.env.PLASMO_PUBLIC_SHIELD_FREQUENCY)

// Will be undefined because it's not prefixed with PLASMO_PUBLIC_
console.log(process.env.PRIVATE_KEY)
```

See [with-env](https://github.com/PlasmoHQ/examples/tree/main/with-env) for more details about using .env variables.

### In Remote Code Import

Use public environment variables if you are [importing remote code](/framework/remote-code):

```tsx
import "https://www.plasmo.com/js?id=$PLASMO_PUBLIC_ITERO"
```

### In Content Scripts Config

You can also use environment variables in the [content script config exports](/framework/content-scripts#customizing-content-script-config):

```ts
export const config: PlasmoCSConfig = {
  matches: ["$PLASMO_PUBLIC_SITE_URL/"]
}
```

### In Manifest Overrides

Plasmo lets you [override the final generated extension manifest via the `manifest` property of the package.json file](/framework/customization/manifest). Taking one step further, Plasmo also parses any environment variables used in the manifest overrides:

```json
"manifest": {
  "key": "$CRX_PUBLIC_KEY"
}
```

You can use public (prefixed with `PLASMO_PUBLIC`) and private environment variables in your manifest override. 😎

<Callout emoji="⚠️">
  Plasmo will omit the key if it can't find the environment variable.
</Callout>
